组件 API 审查与 AI 辅助打磨
组件写完了不代表做好了。这节用 AI 全面审查组件的 Props、Events、Slots 设计，查漏补缺，打磨到可发布状态。
为什么需要 API 审查
第10-12章写了十几个组件，每个组件的 Props、Events、Slots 都是边开发边设计的。开发过程中容易产生的问题：
- 命名不一致：一个组件用
onSend，另一个用@submit - 缺少类型导出：用户想给 Message 添加自定义字段但类型不允许
- Props 过多或过少：该暴露的没暴露，不该暴露的暴露了
- 缺少默认值：必填的 Props 应该有合理默认值
- Events 缺失：用户需要监听的事件没有暴露
API 审查就是在发布前系统性地检查这些问题。
审查框架
从三个维度审查每个组件：
1. Props 审查
// ChatWindow 的 Props 是否完整？
defineProps<{
title?: string
messages: Message[]
avatar?: string
senderName?: string
loading?: boolean
theme?: 'default' | 'purple' | 'green' | 'warm'
customTheme?: Record<string, string>
darkMode?: boolean | 'auto'
locale?: string
messages?: Record<string, Partial<LocaleMessages>> // 命名冲突！
maxInputLength?: number
placeholder?: string
disabled?: boolean
}>()
typescript
审查要点：
- 命名冲突：
messages同时作为 Props 和 i18n 翻译字典的 key，需要改为i18nMessages - 缺少
placeholder的默认值 disabled应该影响哪些子组件？
2. Events 审查
// 所有组件应该暴露哪些事件？
const emit = defineEmits<{
send: [text: string, files?: File[]]
abort: []
clear: []
imagePreview: [index: number]
messageClick: [message: Message]
error: [error: Error]
}>()
typescript
审查要点：
error事件是否所有错误场景都会触发？- 用户如何知道消息发送成功/失败？
- 是否需要
message:updated事件？
3. Slots 审查
<!-- 每个组件的 slot 是否合理？ -->
<slot name="header" />
<slot name="avatar" />
<slot name="message" :message="msg" :index="i" />
<slot name="empty" />
<slot name="footer" />
typescript
审查要点：
- 作用域 slot 是否传了足够的数据？
- 是否缺少关键 slot（如
tool-call、attachment）？ - slot 的 fallback 内容是否合理？
用AI做自动化审查
核心提示词：
审查 @ai-chat/vue 包中所有组件的 API 设计，输出审查报告。
审查维度：
1. Props：命名一致性、类型正确性、默认值合理性、是否有遗漏
2. Events：是否覆盖所有用户需要的交互场景、参数类型是否正确
3. Slots：作用域数据是否完整、是否有遗漏的自定义点
4. 类型导出：用户需要但未导出的类型
5. 向后兼容：破坏性变更的风险
输出格式：
- 每个组件一个表格
- 标记问题级别：ERROR（必须修复）/ WARN（建议修复）/ INFO（可优化）
- 给出具体修复建议
text
AI 会扫描所有 .vue 文件的 defineProps、defineEmits、<slot> 定义，生成结构化审查报告。
具体修复示例
修复命名冲突
// 之前：messages 既用于聊天消息又用于 i18n
defineProps<{
messages: Message[]
messages?: Record<string, Partial<LocaleMessages>>
}>()
// 之后：i18n 翻译字典改名为 localeMessages
defineProps<{
messages: Message[]
localeMessages?: Record<string, Partial<LocaleMessages>>
}>()
typescript
补充缺失的类型导出
// packages/vue/src/index.ts
export type { Message, StreamChunk, ChatAdapter, Attachment, ToolCall } from '@ai-chat/core'
export type { Conversation } from '@ai-chat/core'
export type { LocaleMessages, Locale } from './i18n/types'
// 组件 Props 类型也导出
export type { ChatWindowProps } from './components/ChatWindow.vue'
typescript
补充缺失的事件
// MessageBubble 补充事件
const emit = defineEmits<{
copy: [content: string] // 复制消息内容
retry: [messageId: string] // 重试发送
reaction: [messageId: string, type: string] // 消息反馈
}>()
typescript
补充缺失的 Slots
<!-- ChatWindow 新增 slot -->
<slot name="tool-call" :tool-call="tc">
<ToolCallPanel :tool-call="tc" />
</slot>
<slot name="attachment" :attachment="att">
<FileAttachment :file="att" />
</slot>
vue
编写 API 文档
审查完成后，让 AI 生成组件 API 文档：
基于审查后的组件 API，生成完整的组件文档。
格式：每个组件一个章节，包含：
1. 组件描述（一句话）
2. Props 表格（名称/类型/默认值/说明）
3. Events 表格（名称/参数/说明）
4. Slots 表格（名称/作用域数据/说明）
5. 基本用法示例
6. 高级用法示例（主题定制/自定义渲染）
text
这份文档既是对外发布的使用文档，也是后续维护的参考。
小结
- API 审查三个维度：Props（命名/类型/默认值）、Events（覆盖度/参数）、Slots（数据完整性）
- AI 自动扫描组件代码，生成结构化审查报告，标记问题级别
- 常见问题：命名冲突、类型未导出、事件缺失、slot 数据不够
- 审查完成后用 AI 生成组件 API 文档，作为发布文档
第12章到此结束。我们扩展了组件库的多模态、工具调用、多会话、国际化能力，并用 AI 审查打磨了组件 API。下一章进入测试环节。
↑